home *** CD-ROM | disk | FTP | other *** search
/ PC Direct 1998 August / PC Direct August 1998.iso / S / powerj / Product / hpp.z / WDATASRC.HPP < prev    next >
Encoding:
C/C++ Source or Header  |  1997-11-25  |  18.3 KB  |  593 lines
  1.  
  2. #ifndef _WDATASRC_HPP_INCLUDED
  3. #define _WDATASRC_HPP_INCLUDED
  4.  
  5. //-----------------------------------------------------------------------
  6. //
  7. // Interfaces used to implement the binding of objects to data sources.
  8. //
  9. // These interfaces are meant to be embedded in other objects.  All
  10. // methods are virtual so that specializations can be created.
  11. //
  12. //-----------------------------------------------------------------------
  13.  
  14. #ifndef _WDATAERR_HPP_INCLUDED
  15. #include "wdataerr.hpp"
  16. #endif
  17. #ifndef _WDATATRG_HPP_INCLUDED
  18. #include "wdatatrg.hpp"
  19. #endif
  20.  
  21. enum WDSMoveType {
  22.     WDSMoveNext     = SQL_FETCH_NEXT,
  23.     WDSMoveFirst    = SQL_FETCH_FIRST,
  24.     WDSMoveLast     = SQL_FETCH_LAST,
  25.     WDSMovePrevious = SQL_FETCH_PRIOR,
  26.     WDSMoveAbsolute = SQL_FETCH_ABSOLUTE,
  27.     WDSMoveRelative = SQL_FETCH_RELATIVE,
  28.     WDSMoveBookmark = SQL_FETCH_BOOKMARK
  29. };
  30.  
  31. enum WDSEditMode {
  32.     WDSEditModeRead,   // just reading
  33.     WDSEditModeEdit,   // editing current row
  34.     WDSEditModeAdd     // adding a new row
  35. };
  36.  
  37. //
  38. // Declare the classes for state information
  39. //
  40.  
  41. typedef void *WDataSourceState;
  42.  
  43. //
  44. // WDataSource -- An interface exposed by an object which has data
  45. //                that is to be bound to other objects.
  46. //
  47.  
  48. class WCMCLASS WDataSource : public WEventGenerator {
  49.  
  50.     WDeclareSubclass( WDataSource, WEventGenerator );
  51.  
  52.     private:
  53.  
  54.         WDataSource( const WDataSource & );
  55.         WDataSource& operator=( const WDataSource & );
  56.  
  57.     public:
  58.  
  59.         WDataSource();
  60.  
  61.         ~WDataSource();
  62.  
  63.         /*********************************************************
  64.          * Operators
  65.          *********************************************************/
  66.  
  67.         // operator[]
  68.  
  69.         const WDataColumn & operator[]( WShort i ) const;
  70.         const WDataColumn & operator[]( const WString & name ) const;
  71.  
  72.         /*********************************************************
  73.          * Properties
  74.          *********************************************************/
  75.  
  76.         // AlwaysReadWriteTargets
  77.         //
  78.         //    If TRUE, enables targets to be enabled for read and write 
  79.         //    even when the data source is read only
  80.  
  81.         virtual WBool GetAlwaysReadWriteTargets() const;
  82.         virtual WBool SetAlwaysReadWriteTargets( WBool enable );
  83.  
  84.         // AutoEdit
  85.         //
  86.         //    If TRUE, data targets will automatically engage edit mode
  87.         //    when their value is changed.
  88.  
  89.         virtual WBool GetAutoEdit() const;
  90.         virtual WBool SetAutoEdit( WBool autoEdit );
  91.  
  92.         // AutoRefresh
  93.         //
  94.         //    If TRUE, updates and deletes will appear immediately in any
  95.         //    attached data targets.
  96.  
  97.         virtual WBool GetAutoRefresh() const;
  98.         virtual WBool SetAutoRefresh( WBool autoRefresh );
  99.  
  100.         // BOF
  101.         //
  102.         //    Returns TRUE if the cursor is positioned before the
  103.         //    first row in the result set.
  104.  
  105.         virtual WBool GetBOF() const;
  106.  
  107.         // Bookmark
  108.         //
  109.         //    Returns an integer which is used as a bookmark for
  110.         //    the current row.  You can move to it using the MoveBookmark
  111.         //    method.
  112.  
  113.         virtual WDWord GetBookmark() const;
  114.  
  115.         // Column
  116.         //
  117.         //    Return a specific column, either by index (columns
  118.         //    start at 0) or by name.
  119.  
  120.         virtual const WDataColumn & GetColumn( WShort index ) const;
  121.         virtual const WDataColumn & GetColumn( const WString & name ) const;
  122.  
  123.         // ColumnCount
  124.         //
  125.         //    Return the number of columns available (note that column 0
  126.         //    is always a special column).
  127.  
  128.         virtual WShort GetColumnCount() const;
  129.  
  130.         // ColumnIndex
  131.         //
  132.         //    Return the index of a column given its name.  Returns -1
  133.         //    on error.
  134.  
  135.         virtual WShort GetColumnIndex( const WString & str ) const;
  136.  
  137.         // CurrentRow
  138.         //
  139.         //    The current row (rows start at 1), if known.
  140.  
  141.         virtual WLong GetCurrentRow() const;
  142.  
  143.         // EditMode
  144.         //
  145.         //    The current edit mode.
  146.  
  147.         virtual WDSEditMode GetEditMode() const;
  148.  
  149.         // EOF
  150.         //
  151.         //    Returns TRUE if the cursor is positioned after the
  152.         //    last row in the result set.
  153.  
  154.         virtual WBool GetEOF() const;
  155.  
  156.         // Empty
  157.         //
  158.         //    Returns TRUE if the result set is empty (no rows)
  159.         //    or null (no columns).
  160.  
  161.         virtual WBool GetEmpty() const;
  162.  
  163.         // ErrorCode
  164.         //
  165.         //    Returns the error code of the last operation.
  166.         //    Can optionally return a code specifying which driver
  167.         //    API was called (driver-specific).
  168.  
  169.         virtual WLong GetErrorCode( WLong *apiCode=NULL ) const;
  170.  
  171.         // ErrorList
  172.         //
  173.         //    Returns the list of errors from the last operation.
  174.  
  175.         virtual WDataErrorArray GetErrorList() const;
  176.  
  177.         // ForwardOnly
  178.         //
  179.         //    Returns TRUE if moves are only allowed in the forward
  180.         //    direction.
  181.  
  182.         virtual WBool GetForwardOnly() const;
  183.  
  184.         // Null
  185.         //
  186.         //    Returns TRUE if the result set is null (no columns).
  187.         //    This is NOT the same as an empty result set.
  188.  
  189.         virtual WBool GetNull() const;
  190.  
  191.         // Opened
  192.         //
  193.         //    Returns TRUE if the datasource is "open" (it has data).
  194.  
  195.         virtual WBool GetOpened() const;
  196.  
  197.         // RawData
  198.         //
  199.         //    Fetch data directly from the data source, bypassing
  200.         //    any binding that may have occurred.  Use this to get
  201.         //    chunks of data.
  202.  
  203.         virtual WBool GetRawData( WShort index, WNativeDataType type,
  204.                                   void *buffer, WLong bufferSize=0,
  205.                                   WLong *bytesRemaining=NULL ) const;
  206.  
  207.         // ReadOnly
  208.         //
  209.         //    If TRUE, no changes can be made to the data source.
  210.  
  211.         virtual WBool GetReadOnly() const;
  212.  
  213.         // RowChanged
  214.         //
  215.         //    If TRUE, one or more of the values in the row may need
  216.         //    to be updated.
  217.  
  218.         virtual WBool GetRowChanged() const;
  219.         virtual WBool SetRowChanged( WBool changed );
  220.  
  221.         // RowCount
  222.         //
  223.         //    Returns the number of rows.  This may be expensive to call,
  224.         //    as it may force rows to be counted one by one.  If you pass
  225.         //    in FALSE, it simply uses the last known row count value,
  226.         //    which may be -1 if the count is not yet known.
  227.         //    If you just need to know whether a result set is empty or null,
  228.         //    see the Empty and Null properties instead.
  229.  
  230.         virtual WLong GetRowCount( WBool forceCount=TRUE ) const;
  231.  
  232.         // RowTargetChanged
  233.         //
  234.         //    If TRUE, one or more of the values in the row
  235.         //    was changed but the data source is readonly
  236.  
  237.         virtual WBool GetRowTargetChanged() const;
  238.         virtual WBool SetRowTargetChanged( WBool changed );
  239.  
  240.         // TargetsEnabled
  241.         //
  242.         //    Enable or disable the targets.  Disabling does not do a
  243.         //    clear, merely prevents them from updating themselves.
  244.  
  245.         virtual WBool GetTargetsEnabled() const;
  246.         virtual WBool SetTargetsEnabled( WBool enabled );
  247.  
  248.         // ThreadSafe
  249.         //
  250.         //    If TRUE, the object can be accessed safely from different
  251.         //    threads and the ThreadLock/ThreadUnlock methods are enabled.
  252.  
  253.         virtual WBool GetThreadSafe() const;
  254.         virtual WBool SetThreadSafe( WBool safe );
  255.  
  256.         // Value
  257.         //
  258.         //    Set/get the value of a particular column in the
  259.         //    current row.  See RawData as well.
  260.  
  261.         virtual WDataValue GetValue( WShort index,
  262.                                      WNativeDataType type=SQL_C_DEFAULT ) const = 0;
  263.         virtual WBool      SetValue( WShort index, const WDataValue & val ) = 0;
  264.  
  265.         /*********************************************************
  266.          * Methods
  267.          *********************************************************/
  268.  
  269.         // Add
  270.         //
  271.         //    Prepare to add a new row.  Returns FALSE if there are no
  272.         //    updatable columns or the query is read-only.  After setting
  273.         //    the new values with SetValue, call Update to actually
  274.         //    add the new row.  Call CancelUpdate to cancel any pending
  275.         //    add.
  276.  
  277.         virtual WBool Add( WBool copyValues=FALSE, WBool append=FALSE,
  278.                            WBool copyIntoBuffer=FALSE );
  279.  
  280.         // CancelUpdate
  281.         //
  282.         //    Cancel a pending update or add operation.
  283.  
  284.         virtual WBool CancelUpdate( WBool notifyTargets=TRUE );
  285.  
  286.         // ClearTargets
  287.         //
  288.         //    Tell any targets to clear themselves.
  289.  
  290.         virtual WBool ClearTargets();
  291.  
  292.         // Close
  293.         //
  294.         //    Close the current query, if any.
  295.  
  296.         virtual WBool Close( WBool discardResults=TRUE,
  297.                              WBool isRequery=FALSE );
  298.  
  299.         // Delete
  300.         //
  301.         //    Deletes the current row.
  302.  
  303.         virtual WBool Delete( WBool triggerEvent=TRUE,
  304.                               WBool notifyTargets=TRUE );
  305.  
  306.         // Edit
  307.         //
  308.         //    Prepare the current row for editing.  Returns FALSE if
  309.         //    there are no updatable columns or the query is read-only.
  310.         //    After setting the new values with SetValue, call Update
  311.         //    to actually update the row.  Call CancelUpdate to cancel
  312.         //    any pending add.
  313.  
  314.         virtual WBool Edit();
  315.  
  316.         // MoreResults
  317.         //
  318.         //    Closes the current result set and opens the next
  319.         //    result set, if any.  Returns TRUE if a new result
  320.         //    set is available and open, FALSE otherwise.
  321.  
  322.         virtual WBool MoreResults();
  323.  
  324.         // Move
  325.         //
  326.         //    General move routine for navigating through the data
  327.         //    source.  By default does an absolute move.
  328.  
  329.         virtual WBool Move( WLong row, WBool notifyTargets=TRUE,
  330.                             WDSMoveType type=WDSMoveAbsolute,
  331.                             WBool triggerEvents=TRUE );
  332.  
  333.         // MoveBookmark
  334.         //
  335.         //    Move to a bookmark.
  336.  
  337.         WBool MoveBookmark( WDWord bookmark, WBool notify=TRUE,
  338.                             WBool triggerEvents=TRUE );
  339.  
  340.         // MoveFirst
  341.         //
  342.         //    Move to the first row.
  343.  
  344.         WBool MoveFirst( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  345.  
  346.         // MoveLast
  347.         //
  348.         //    Move to the last row.
  349.  
  350.         WBool MoveLast( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  351.  
  352.         // MoveNext
  353.         //
  354.         //    Move to the next row.
  355.  
  356.         WBool MoveNext( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  357.  
  358.         // MovePrevious
  359.         //
  360.         //    Move to the previous row.
  361.  
  362.         WBool MovePrevious( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  363.  
  364.         // MoveRelative
  365.         //
  366.         //    Move to a relative row.
  367.  
  368.         WBool MoveRelative( WLong offset, WBool notifyTargets=TRUE,
  369.                             WBool triggerEvents=TRUE );
  370.  
  371.         // Open
  372.         //
  373.         //    Execute the SQL statement and open the result set for
  374.         //    processing.
  375.  
  376.         virtual WBool Open( WBool executeStatement=TRUE,
  377.                             WBool isRequery=FALSE );
  378.  
  379.         // Refresh
  380.         //
  381.         //    Refresh (re-read) all of the data. The cursor is position is
  382.         //    retained if possible.
  383.  
  384.         virtual WBool Refresh();
  385.  
  386.         // RefreshTargets
  387.         //
  388.         //    Refresh the targets, causing them to re-read their values
  389.         //    for the current row.  Can optionally specify whether
  390.         //    multirow targets should reread all their values.
  391.  
  392.         virtual WBool RefreshTargets( WBool multiRow=FALSE );
  393.  
  394.         // RestoreState
  395.         //
  396.         //    Restore the data source's state to a previously saved
  397.         //    value.
  398.  
  399.         virtual WBool RestoreState( const WDataSourceState state,
  400.                                     WBool restore=TRUE );
  401.  
  402.         // SaveState
  403.         //
  404.         //    Save the state of a data source.  What gets saved
  405.         //    depends on the data source.  It might be a bookmark,
  406.         //    it might be much more.
  407.  
  408.         virtual WBool SaveState( WDataSourceState & state );
  409.  
  410.         // SearchUsingTargets
  411.         //
  412.         //    Do a search based on current target values.  How this
  413.         //    affects the result set is up to the data source.
  414.  
  415.         virtual WBool SearchUsingTargets();
  416.  
  417.         // ThreadLock
  418.         //
  419.         //    Lock access to the data source to the thread that
  420.         //    calls this function.  Can specify what to do if
  421.         //    the thread is already locked.  Note that once a
  422.         //    thread is locked care must be taken in calling
  423.         //    methods that may trigger events or notify targets,
  424.         //    since deadlock can occur.
  425.  
  426.         virtual WBool ThreadLock( WBool wait=TRUE, WDWord timeout=0xFFFFFFFF );
  427.  
  428.         // ThreadUnlock
  429.         //
  430.         //    Unlock the data source.  Returns TRUE if the source is no
  431.         //    longer locked (or was never locked) by the calling thread.
  432.  
  433.         virtual WBool ThreadUnlock();
  434.  
  435.         // Update
  436.         //
  437.         //    Update the row (either the current row or a row that is
  438.         //    being added) to the database.  Can optionally cause a
  439.         //    ValidateData event to be triggered.
  440.  
  441.         virtual WBool Update( WBool triggerEvent=TRUE,
  442.                               WBool notifyTargets=TRUE );
  443.  
  444.         /*********************************************************
  445.          * Other
  446.          *********************************************************/
  447.  
  448.         // DataAvailable
  449.         //
  450.         //    Call the DataAvailable method on all registered targets.
  451.  
  452.         virtual WBool DataAvailable( WLong row,
  453.                                      WULong reason,
  454.                                      WULong suggestedAction,
  455.                                      WBool multiValueOnly );
  456.  
  457.         // DataClose
  458.         //
  459.         //    Call the DataClose method on all registered targets.
  460.  
  461.         virtual WBool DataClose( WBool isRequery );
  462.  
  463.         // DataOpen
  464.         //
  465.         //    Call the DataOpen method on all registered targets.
  466.  
  467.         virtual WBool DataOpen( WBool isRequery );
  468.  
  469.         // DataRequest
  470.         //
  471.         //    Call the DataRequest method on all registered targets.
  472.  
  473.         virtual WBool DataRequest( WULong reason, WULong suggestedAction,
  474.                                    WBool touched=FALSE );
  475.  
  476.         // RemoveAllTargets
  477.         //
  478.         //    Call SetDataSource(NULL) on each target object.
  479.  
  480.         virtual WBool RemoveAllTargets();
  481.  
  482.         /*********************************************************
  483.          * Target Methods (only targets should call these)
  484.          *********************************************************/
  485.  
  486.         // AddTarget
  487.         //
  488.         //    DataTarget objects call this method to register themselves
  489.         //    with a data source.
  490.  
  491.         virtual WBool AddTarget( WDataTarget *target );
  492.  
  493.         // BindTarget
  494.         //
  495.         //    DataTarget objects call this method when processing a
  496.         //    DataOpen event to let the source know which columns
  497.         //    they are interested in.
  498.  
  499.         virtual WBool BindTarget( WDataTarget *target, WShort column,
  500.                                   WNativeDataType type=SQL_C_DEFAULT );
  501.  
  502.         // RemoveTarget
  503.         //
  504.         //    DataTarget objects call this method to deregister themselves.
  505.  
  506.         virtual WBool RemoveTarget( WDataTarget *target );
  507.  
  508.     public:
  509.  
  510.         wllist_header & GetTargetListHeader();
  511.         wllist_header & GetBindListHeader();
  512.         void            ClearBindList();
  513.  
  514.         WBool GetTargetRowExtents( WLong & firstRow, WLong & lastRow );
  515.  
  516.     protected:
  517.  
  518.         // List of registered targets...
  519.  
  520.         struct WTargetEntry {
  521.             wllist_link      link;
  522.             WDataTarget     *target;
  523.             WDataTargetType  type;
  524.             WShort           firstColumn; // first column bound to the control
  525.         };
  526.  
  527.         WTargetEntry *FindTarget( WDataTarget *target );
  528.         WBool         SortTargets();
  529.  
  530.         // List of binding suggestions...
  531.  
  532.         struct WBindEntry {
  533.             wllist_link      link;
  534.             WShort           column;
  535.             WDataTarget     *target;
  536.             WNativeDataType  type;
  537.         };
  538.  
  539.         wllist_header        _targetList;
  540.         wllist_header        _bindList;
  541.         WLong                _row;
  542.         WBool                _rowChanged;
  543.         WBool                _targetsEnabled;
  544.         WBool                _alwaysReadWriteTargets;
  545.         WBool                _rowTargetChanged;
  546. };
  547.  
  548. typedef WEventData WAdjustCursorEventData;
  549. typedef WEventData WFetchDataEventData;
  550. typedef WEventData WMoveCursorEventData;
  551. typedef WEventData WBeginFetchDataEventData;
  552. typedef WEventData WBeginMoveCursorEventData;
  553. typedef WEventData WQueryBusyEventData;
  554. typedef WEventData WQueryPrepareEventData;
  555.  
  556. enum WDSValidateAction {
  557.     WDSVAMoveNext     = WDSMoveNext,
  558.     WDSVAMoveFirst    = WDSMoveFirst,
  559.     WDSVAMoveLast     = WDSMoveLast,
  560.     WDSVAMovePrevious = WDSMovePrevious,
  561.     WDSVAMoveAbsolute = WDSMoveAbsolute,
  562.     WDSVAMoveRelative = WDSMoveRelative,
  563.     WDSVAMoveBookmark = WDSMoveBookmark,
  564.     WDSVAUpdateCurrentRow,
  565.     WDSVAUpdateNewRow,
  566.     WDSVADeleteCurrentRow,
  567. };
  568.  
  569. struct WQueryOpenEventData : public WEventData {
  570.     WBool isRequery;
  571. };
  572.  
  573. struct WQueryCloseEventData : public WEventData {
  574.     WBool isRequery;
  575. };
  576.  
  577. struct WValidateDataEventData : public WEventData {
  578.     WDSValidateAction action;    // action about to happen
  579.     WLong             row;       // row data for action
  580.     WBool             cancel;    // set to TRUE to cancel the action
  581.     WBool             update;    // if TRUE, data is updated before move
  582.  
  583.     //
  584.     // Use when updatePolicy of query object is WQUPUserDefine.
  585.     //
  586.     // The user should set this to TRUE when successful update to the
  587.     // current row in the event handler has been done.
  588.     //
  589.     WBool             hasPerformedUpdate;
  590. };
  591.  
  592. #endif
  593.